/*
    * Copyright (C) 2012 The Guava Authors
    *
    * Licensed under the Apache License, Version 2.0 (the "License");
    * you may not use this file except in compliance with the License.
    * You may obtain a copy of the License at
    *
    * http://www.apache.org/licenses/LICENSE-2.0
    *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package com.google.common.collect;
  
  import static com.google.common.base.Preconditions.checkNotNull;
  
  import com.google.common.annotations.Beta;
  import com.google.common.annotations.GwtCompatible;
  
  import java.util.ArrayDeque;
  import java.util.Deque;
  import java.util.Iterator;
  import java.util.Queue;
  
  /**
   * Views elements of a type {@code T} as nodes in a tree, and provides methods to traverse the trees
   * induced by this traverser.
   *
   * <p>For example, the tree
   *
   * <pre>          {@code
   *          h
   *        / | \
   *       /  e  \
   *      d       g
   *     /|\      |
   *    / | \     f
   *   a  b  c       }</pre>
   *
   * <p>can be iterated over in preorder (hdabcegf), postorder (abcdefgh), or breadth-first order
   * (hdegabcf).
   *
   * <p>Null nodes are strictly forbidden.
   *
   * @author Louis Wasserman
   * @since 15.0
   */
  @Beta
  @GwtCompatible(emulated = true)
  public abstract class TreeTraverser<T> {
    // TODO(user): make this GWT-compatible when we've checked in ArrayDeque emulation
  
    /**
     * Returns the children of the specified node.  Must not contain null.
     */
    public abstract Iterable<T> children(T root);
  
    /**
     * Returns an unmodifiable iterable over the nodes in a tree structure, using pre-order
     * traversal. That is, each node's subtrees are traversed after the node itself is returned.
     *
     * <p>No guarantees are made about the behavior of the traversal when nodes change while
     * iteration is in progress or when the iterators generated by {@link #children} are advanced.
     */
    public final FluentIterable<T> preOrderTraversal(final T root) {
      checkNotNull(root);
      return new FluentIterable<T>() {
        @Override
        public UnmodifiableIterator<T> iterator() {
          return preOrderIterator(root);
        }
      };
    }
  
    // overridden in BinaryTreeTraverser
    UnmodifiableIterator<T> preOrderIterator(T root) {
      return new PreOrderIterator(root);
    }
  
    private final class PreOrderIterator extends UnmodifiableIterator<T> {
      private final Deque<Iterator<T>> stack;
  
      PreOrderIterator(T root) {
        this.stack = new ArrayDeque<Iterator<T>>();
        stack.addLast(Iterators.singletonIterator(checkNotNull(root)));
      }
  
      @Override
      public boolean hasNext() {
        return !stack.isEmpty();
      }
  
      @Override
      public T next() {
        Iterator<T> itr = stack.getLast(); // throws NSEE if empty
       T result = checkNotNull(itr.next());
       if (!itr.hasNext()) {
         stack.removeLast();
       }
       Iterator<T> childItr = children(result).iterator();
       if (childItr.hasNext()) {
         stack.addLast(childItr);
       }
       return result;
     }
   }
 
   /**
    * Returns an unmodifiable iterable over the nodes in a tree structure, using post-order
    * traversal. That is, each node's subtrees are traversed before the node itself is returned.
    *
    * <p>No guarantees are made about the behavior of the traversal when nodes change while
    * iteration is in progress or when the iterators generated by {@link #children} are advanced.
    */
   public final FluentIterable<T> postOrderTraversal(final T root) {
     checkNotNull(root);
     return new FluentIterable<T>() {
       @Override
       public UnmodifiableIterator<T> iterator() {
         return postOrderIterator(root);
       }
     };
   }
 
   // overridden in BinaryTreeTraverser
   UnmodifiableIterator<T> postOrderIterator(T root) {
     return new PostOrderIterator(root);
   }
 
   private static final class PostOrderNode<T> {
     final T root;
     final Iterator<T> childIterator;
 
     PostOrderNode(T root, Iterator<T> childIterator) {
       this.root = checkNotNull(root);
       this.childIterator = checkNotNull(childIterator);
     }
   }
 
   private final class PostOrderIterator extends AbstractIterator<T> {
     private final ArrayDeque<PostOrderNode<T>> stack;
 
     PostOrderIterator(T root) {
       this.stack = new ArrayDeque<PostOrderNode<T>>();
       stack.addLast(expand(root));
     }
 
     @Override
     protected T computeNext() {
       while (!stack.isEmpty()) {
         PostOrderNode<T> top = stack.getLast();
         if (top.childIterator.hasNext()) {
           T child = top.childIterator.next();
           stack.addLast(expand(child));
         } else {
           stack.removeLast();
           return top.root;
         }
       }
       return endOfData();
     }
 
     private PostOrderNode<T> expand(T t) {
       return new PostOrderNode<T>(t, children(t).iterator());
     }
   }
 
   /**
    * Returns an unmodifiable iterable over the nodes in a tree structure, using breadth-first
    * traversal. That is, all the nodes of depth 0 are returned, then depth 1, then 2, and so on.
    *
    * <p>No guarantees are made about the behavior of the traversal when nodes change while
    * iteration is in progress or when the iterators generated by {@link #children} are advanced.
    */
   public final FluentIterable<T> breadthFirstTraversal(final T root) {
     checkNotNull(root);
     return new FluentIterable<T>() {
       @Override
       public UnmodifiableIterator<T> iterator() {
         return new BreadthFirstIterator(root);
       }
     };
   }
 
   private final class BreadthFirstIterator extends UnmodifiableIterator<T>
       implements PeekingIterator<T> {
     private final Queue<T> queue;
 
     BreadthFirstIterator(T root) {
       this.queue = new ArrayDeque<T>();
       queue.add(root);
     }
 
     @Override
     public boolean hasNext() {
       return !queue.isEmpty();
     }
 
     @Override
     public T peek() {
       return queue.element();
     }
 
     @Override
     public T next() {
       T result = queue.remove();
       Iterables.addAll(queue, children(result));
       return result;
     }
   }
 }